I'm curious if this needs to be in docs/specification/overview.md, as this should be true for all extensions, correct?

Good call — partial adoption is indeed a general extension pattern. I'll open a follow-up to add guidance in overview.md about how platforms should handle extensions that declare multiple extends entries. For now the note stays here so this spec is self-contained, but the broader principle should live in the overview.

Should this table be here under docs/specification/fee.md or should fee.md just call out the new total type? I ask because it could make the docs harder to maintain if every extension that affects totals recreates the totals table (e.g. Discount also could have this table).

Fair concern about maintenance. I kept the table here so the fee spec is self-contained for readers — but you're right that if every extension duplicates it, drift is inevitable. For now I'll keep it with a note that the canonical source is the checkout/totals spec. We could consider a shared include or a cross-reference pattern in a follow-up.

This language is helpful, and we should consider being this crisp with the other total types.

Thanks — agreed, we should bring this level of precision to the other total types as well. Happy to help with that in a follow-up pass across the spec.

Even if the discrepancy is surfaced, is it appropriate for the platform to proceed? Should the Platform use the continue_url is such a case? If yes, should the continue_url be a required field? Currently, it doesn't seem like we have a good way for platforms to handle these cases.

Great question. Updated in d03ce30 — softened the language from "MUST NOT complete" to "SHOULD surface the discrepancy" and explicitly added continue_url as a fallback option:

Platforms MAY use continue_url to hand off to the business UI for resolution rather than attempting to complete the checkout with inconsistent fee data.

I didn't make continue_url required since it's already an optional field on checkout — making it required just for fee mismatch cases would be a broader spec change. But the guidance now gives platforms a clear escape hatch.

This still feels a bit ambiguous. Does this note deserve the same normative language as the Invariant above? That is, "totals[type=fee] MUST represent the aggregated fee total"; or alternatively, something about there MAY be n number of totals[type=fee] objects in totals (the question that sparked issue #219 ).

Updated in d03ce30 — the admonition now uses explicit normative language:

When the Fee Extension is present, there MUST be at most one totals[] entry with type: "fee", and its amount MUST equal sum(fees.applied[].amount). When the Fee Extension is not advertised, the interpretation of any totals[type=fee] entry is business-defined — platforms SHOULD render it using display_text but MUST NOT assume itemized fee data is available.

This addresses both the "how many fee totals?" question from #219 and the absent-extension semantics.

We should adopt this across the spec. In other places we are simply saying "minor units (cents)" which is inadequate for all currencies.

Agreed — "minor units (cents)" is USD-centric and inadequate. Happy to help with a follow-up sweep to adopt consistent ISO 4217 language across all monetary fields in the spec.

Are fee ids expected to be consistent across checkout sessions? Or just across requests within a checkout session or cart?

Within a session only. Updated in d03ce30 — both the schema description and the docs now clarify:

Fee IDs are scoped to a single checkout or cart session. The same fee retains its id across requests within a session (create → update → complete), but the id is not guaranteed to be consistent across separate sessions. Businesses control ID generation.

This gives platforms stable tracking within a session (which is the primary use case for UI diffing) without imposing a cross-session uniqueness burden on businesses.

Also human-readable, I assume. As with conversations around disclosure, I wonder how Platforms should navigate Businesses potentially wanting richer text, or even images.

Updated in d03ce30 — the description field is now explicitly marked as plain text in both the schema and the spec. For richer content needs, the spec now includes a forward reference:

The description field is plain text — for richer content such as regulatory disclosures, images, or formatted copy, businesses should use the Disclosures capability (see #222) when available.

This keeps the fee schema simple while pointing to the right extension point for richer content.

What is the value of this spec defining types, especially so many of them? Does a Platform need to know the various types?

The well-known types serve interoperability — they let platforms build smarter UX when they recognize a type (e.g., grouping all recycling fees, or showing a specific icon for service fees). But they're explicitly not prescriptive: fee_type is an open string, unknown values are fine, and platforms SHOULD fall back to displaying the title.

Think of it like HTTP status codes — the well-known ones enable richer behavior, but the system works with unknown ones too. The table documents common patterns we've seen across commerce platforms to reduce the "what should I call this?" guesswork.

Is there perhaps a need to communicate to the Platform / User that a fee was waived? If we do not allow zero-amount fees, how should this be communicated in the response?

Great question. Updated in d03ce30 — added guidance for using messages[] to communicate waived fees:

{
  "messages": [
    {
      "type": "info",
      "code": "fee_waived",
      "content": "Service Fee waived for loyalty members."
    }
  ]
}

This uses the existing messages mechanism rather than inventing a fee-specific signaling pattern. The code: "fee_waived" gives platforms something to key on programmatically, and the content provides the human-readable explanation.

Shall we add an error code to source/schemas/shopping/types/error_code.json for this?

Done in d03ce30 — added readonly_field_not_allowed to source/schemas/shopping/types/error_code.json examples, and referenced it in the fee spec:

Businesses SHOULD use the readonly_field_not_allowed error code when rejecting such requests.

This follows the existing pattern where error_code.json uses examples (not enum) for well-known codes.

This made me think of #222 . Is a plain-text description adequate, or are there fees that may need to be more expressive; perhaps we handle those with disclosures?

Exactly — same thought. Updated in d03ce30 to add a forward reference to #222:

The description field is plain text — for richer content such as regulatory disclosures, images, or formatted copy, businesses should use the Disclosures capability (see #222) when available.

Plain text covers the 80% case (simple one-liner like "State-mandated recycling fee"). For the 20% that needs formatted copy, images, or regulatory legalese, Disclosures is the right extension point. Keeping description as plain text avoids the sanitization complexity of allowing HTML/markdown in every fee object.

Suggestion: While the current language allows for independent extension of cart and checkout, we should still guide implementors to ensure a stable state machine and avoid 'price surprises.' Late-stage disclosure is particularly disruptive for platform budget validation and agentic flows.

I suggest adding a perspective on the expected merchant/customer experience to maximize transparency:

1. Early Disclosure: A business SHOULD include fees at the cart level whenever the fee criteria (e.g., item types or subtotal thresholds) are known. Fees SHOULD NOT be deferred to checkout unless they are strictly dependent on data only available at that stage (e.g., payment method surcharges).

2. Disclosure Continuity: A business SHOULD include fees at checkout if they were provided at the cart level to ensure continuity of disclosure granularity and avoid a 'lossy' state transition.

This helps ensures that the merchant-controlled portion of the cost is deterministic as early as possible and remains consistent throughout the transaction lifecycle.

Thanks for the suggestion — this has been addressed in 47b815d. Added a new "Fee disclosure timing" admonition right after the "Partial adoption" note with both of your recommended guidelines:

1. Early disclosure: fees SHOULD be surfaced at cart level when criteria are known; SHOULD NOT be deferred to checkout unless dependent on checkout-only data.
2. Disclosure continuity: fees provided at cart level SHOULD carry through to checkout to avoid a lossy state transition.

Uses SHOULD-level normative language to keep it guidance rather than a hard requirement.

Suggestion: If sum(fees.applied[].amount) < totals[type=fee].amount escalate. Otherwise, this could put the user in a position where they're paying unspecified fees through an intermediary (the platform) which complicates dispute resolution.

Relatedly, has the TC considered strategies to ensure that the totals in the checkout object itself are consistent (i.e. follow the math you have documented above?) .

Good catch — updated in 81ea0fa. The mismatch language now distinguishes between the two directions:

• Aggregated total exceeds itemized sum: platform MUST treat as an error and MUST NOT complete checkout — the user would otherwise pay unspecified fees through an intermediary, complicating dispute resolution. Platforms SHOULD use continue_url for resolution.
• Aggregated total less than itemized sum: platform SHOULD surface the discrepancy but MAY proceed, since the user is not being overcharged.

Regarding TC strategies for totals consistency validation — that's a great broader question. The invariant enforcement here is fee-specific, but a general totals consistency check (ensuring the math holds across all total types) would be a valuable follow-up discussion for the TC. Happy to open an issue for that.

Nit: restocking is a post-purchase/reverse-logistics event. Omit it for the time being?

Agreed — removed in 81ea0fa. Restocking is a post-purchase/reverse-logistics event and doesn't belong in a checkout/cart fee context. It can always be added back later if a returns-specific extension needs it.

Observation: The lack of schema level enforcement here and the one-off carve out for discounts feed into a strong preference for Approach A (#219).

Appreciate the observation. The tension between schema-level enforcement and extension flexibility is real — the current approach (Option B) trades stricter schema coupling for independent extensibility, which was the TC's preference for this iteration. That said, the concern about one-off carve-outs is valid and worth revisiting as more extensions land. If the pattern becomes unwieldy, migrating toward Approach A (or a hybrid) could be a future discussion. Happy to capture this as a tracked consideration if helpful.

Alternative: Polymorphic Composition

We can use JSON Schema's allOf to create a FeeTotal that extends the base Total object which achieves the goal of providing fees structured metadata (per: #219). This allows us to keep a unified totals[] array while providing the "slots" for metadata only when type == fee.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/types/fee_total.json",
  "title": "FeeTotal",
  "allOf": [
    { "$ref": "total.json" },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "fee"
        },
        "description": {
          "type": "string",
          "description": "Optional plain-text explanation of why the fee is charged. For richer content (e.g., regulatory disclosures), see the Disclosures capability."
        },
        "fee_type": {
          "type": "string",
          "description": "Type of fee (open string). Well-known values: service, handling, recycling, processing, regulatory, convenience, restocking, environmental. Platforms SHOULD handle unknown values gracefully by displaying the fee title to the user."
        },
        "taxable": {
          "type": "boolean",
          "default": false,
          "description": "Whether this fee is subject to tax."
        }
      }
    }
  ]
}

Interesting alternative — the polymorphic FeeTotal via allOf composition is a clean pattern. It would keep the unified totals[] array while adding structured metadata slots only when type == fee, which addresses the core goal from #219.

The tradeoff vs. the current approach: it moves fee metadata into the totals array (closer to where the aggregated amount lives) rather than a separate fees extension object. This simplifies the schema graph but means platforms need to handle polymorphic totals entries — some with just type/amount/display_text, others with additional fee-specific fields.

I think this is worth a deeper TC discussion as a potential evolution, especially if other extensions (e.g., fulfillment surcharges) would benefit from the same pattern. Want to open a discussion issue to explore this alongside the Approach A consideration?

Thanks, Maxime -- appreciate the receptiveness to the alternative. I agree that the tradeoff on polymorphic handling is the right pivot to discuss, especially if we can use it to standardize how 'why' metadata is attached to the ledger across other extensions (discounts, fulfillment, etc.).

Per your suggestion, I’ve opened a Discussion issue here to dive into the 'Unified Ledger' pattern: #258

The waivable flag was a bit of an "aha" moment for me that leaves me oppositional to Plan B. It highlights why separating discounts and fees may be a mistake: in any robust POS or financial model, these are simply adjustments to a base price.

The problem with the aggregate-fee with omissions scheme is that merchants (e.g. DoorDash) don't just hide a waived (delivery) fees, they often display the fee as a line item followed by the corresponding credit. This debit-credit pair serves two purposes:

1. Value Signaling: It explicitly proves the discount was applied and reinforces the service's value.
2. Audit Integrity: It maintains a mathematically sound record rather than forcing the platform to guess why a field disappeared or how a taxable fee impacted the final sum.

We should aspire to a totals ledger that is governed by a simple deterministic invariant: total = Subtotal + Sum(Adjustments).

I believe the alternative (#245 (comment)) suggested above may allow you to address the "No structured metadata" limitation of Option A, while avoiding the loose contracts of Option B.